home *** CD-ROM | disk | FTP | other *** search
/ The Arsenal Files 8 / The Arsenal Files Collection #8 (Arsenal Computer) (1996).ISO / windows / filemate.zip / FMDATA.TXT < prev    next >
Text File  |  1996-08-06  |  12KB  |  283 lines
  1. FMDATA.WRI
  2. Chess FileMate for Windows, 4.0
  3. Copyright (c) 1994-1996 William H. Dyche
  4. 74401.3055@compuserve.com
  5.  
  6.  
  7. Contents:
  8.  
  9. 1: Introduction to formats for recorded chess games.
  10.  
  11. 2: Text parsing
  12.  
  13. 3: Rules for writing a PGN game
  14. 3.1: Header Section
  15. 3.2: The Movetext Section
  16. 3.2.1: Move numbers
  17. 3.2.2: Notation
  18. 3.2.3: Move continuation
  19. 3.2.4: Castling indications
  20. 3.2.5: Check, checkmate, and promotion indications
  21. 3.2.6: En-passant
  22. 3.2.7: Commentary
  23. 3.2.8: Variations
  24. 3.2.9: Partial Games
  25.  
  26.  
  27. 1: Introduction to formats for recorded chess games.  
  28.  
  29. In order for software to read information about a game, a convention on
  30. exactly what information is used and how it will be written must be
  31. established and adhered to by the creators of data and software. There have
  32. been several conventions (hereafter referred to as game "formats") in use.
  33. FileMate is designed to automatically recognize and read the formats
  34. referred to as PGN, NIC, and NTR. 
  35.  
  36. PGN, NTR, and NIC are all ASCII text formats, so they can be read by people
  37. as well as programs.  They differ mainly in how the headers are written.  PGN
  38. relies on keywords and a few special characters to clue a program in on what
  39. information is there and where it is located.  The program can then extract
  40. the information and use it, e.g. to create a list of games. NIC also uses
  41. keywords.  NTR is mostly a positional format; it is understood that certain
  42. information will be at certain locations in the header. Examples of all these
  43. formats are in DEMO1.TXT.
  44.  
  45. The PGN format is easiest for a program to deal with because it is simply the
  46. repetition of a little motif:  [keyword "value"].  PGN is well-defined, and
  47. its specifications are publicly available.  It also allows commentary and
  48. embedded variations in the movetext section.
  49.  
  50. Specific information about these formats, as well as a large number of games
  51. files, can be found in the libraries of the CompuServe Chess Forum.  The
  52. format they prefer is PGN.
  53.  
  54.  
  55. 2: Text parsing  (reading and extracting information from text)
  56.  
  57. People are very good at extracting information from text because we have a
  58. vast amount of knowledge with which to analyze such data.  But a program has
  59. only what little knowledge the programmer has been able to (tediously) build
  60. into the program to make sense out of a stream of characters.  A program can
  61. quickly become confused by seemingly trivial typographical errors.
  62.  
  63. On the other hand, the program can read and simply disregard text it doesn't
  64. understand. For example, FileMate can be used to read "The Week In Chess"
  65. files to view the games without having to edit the file or do copy and
  66. pasting.  Just scroll the games list window down to where the games are.
  67.  
  68. Things which can confuse a program:
  69. -  Misuse of special characters. e.g. brackets and quotes in the PGN header
  70.    tell the program where things begin and end.
  71. -  Misuse of blank lines.  Any two games in a file must be separated by one or
  72.    more blank lines.  Within the movetext section, blanks lines can be used
  73.    freely to improve readability in PGN games, but not in NTR and NIC.
  74. -  Each and every PGN game must end with a result string (also called the
  75.    "game termination marker").  The program relies only upon this in
  76.    determining where the text of a PGN game ends.
  77.  
  78. Design of the program's routines for identifying the beginning and end of
  79. games is a compromise between cleverness and quickness.  Don't expect
  80. perfection, e.g. sometimes non-game text may show as NTR in the File window's
  81. games list.
  82.  
  83. As long as you use FileMate to create text, there should not be any data
  84. problems.  The program will generate correct syntax so you won't have to worry
  85. about such technical stuff.  However, some information on syntax is included
  86. here for those who are interested in it.
  87.  
  88.  
  89. 3: Rules for writing a PGN game
  90.  
  91. You can probably write a PGN game by just looking at an example. Each unit in
  92. the header has the form:  [keyword "value"].  The header should always look
  93. like the one you see below except that you supply the values enclosed in
  94. quotes.  There are just a few rules you need to know.
  95.  
  96. -  The keywords must be spelled exactly as you see them in the example. 
  97.    ( "Event", "Site", etc. )
  98. -  The seven keywords shown below should always be present and in the
  99.    same order.
  100. -  The PGN date format is "yyyy.mm.dd".
  101. -  Unknown values are indicated with question marks.
  102. -  A single blank line must separate the header section from the movetext.
  103. -  SAN (Standard Algebraic Notation) must be used.
  104. -  End the movetext section with a result indication:
  105.      0-1, 1-0, 1/2-1/2, or * if unknown result.
  106.  
  107. [Event "?"]
  108. [Site "USSR"]
  109. [Date "1903.??.??"]
  110. [Round "?"]
  111. [White "Salwe,G"]
  112. [Black "Chigorin,M"]
  113. [Result "0-1"]
  114.  
  115. 1. e4 e5 2. Nf3 Nc6 3. Bc4 Bc5 4. d3 Nf6 5. Nc3 d6 6. O-O Bg4 7. Bb5 O-O
  116. 8. Be3 Nd4 9. Bxd4 Bxd4 10. h3 Bh5 11. g4 Bxc3 12. bxc3 Nxg4 13. hxg4 Bxg4
  117. 14. d4 f5 15. Be2 fxe4 16. Nd2 Bxe2 17. Qxe2 Qg5+ 18. Kh1 Rf4 0-1
  118.  
  119.  
  120. 3.1: Header Section
  121.  
  122. PGN specs allow alot of optional information to be included in the header.
  123. For instance, an ECO opening code is often added, e.g. [ECO "B51"].  Many
  124. other officially sanctioned header keywords are documented in the PGN
  125. specifications document.  All are accepted by the program.
  126.  
  127.  
  128. 3.2: The Movetext Section 
  129.  
  130. In PGN terminology, the text containing the moves is called the
  131. "movetext section".  The following is some information about how FileMate
  132. expects the movetext section to be written.  
  133.  
  134. Move legality:
  135. The program will not play illegal moves.  Historical games containing illegal
  136. moves will have to be described and explained in commentary.
  137.  
  138. Standards for data portability:
  139. FileMate will read and display some things which are contrary to format
  140. specifications. e.g. descriptive or other non-algebraic notation, and comments
  141. in NTR and NIC.  But it will only output syntactically correct PGN games
  142. (assuming it is designed correctly).  You should avoid distributing data
  143. which does not conform to generally agreed upon format and notation rules.
  144.  
  145.  
  146. 3.2.1: Move numbers:
  147. Move numbers are optional but highly recommended in PGN.  In FileMate, move
  148. numbers should always be used.  A period appended to the move number is
  149. required also.  The period may be followed by zero or more spaces.
  150.  
  151. 3.2.2: Notation:
  152. The program does very little syntax checking, and no legality checking until
  153. the game is sent to the board.  The program can only read English notation
  154. (piece letters: PRNBQK).
  155.  
  156. 3.2.3: Move continuation:
  157. The program will recognize a move continuation like  10...Bh5.  Notice there
  158. are exactly three periods and no spaces between the number and the play.  PGN 
  159. requires this form whenever a black play follows a comment.
  160.  
  161. 3.2.4: Castling indications:
  162. The use of uppercase letter O's is strongly recomended, although the program 
  163. will accept zeros instead of O's.
  164.  
  165. 3.2.5: Check, checkmate, and promotion indications:
  166. The special characters + and # may be appended to plays to indicate check and 
  167. checkmate.  Pawn promotion may be indicated by a  =  followed by a piece
  168. letter appended to a play (example: b8=Q )  The use of all these indications
  169. is optional, and their validity is not checked by the program.  PGN uses
  170. these indications and no others.  They can be used with all the supported
  171. notations (except that NIC does not use the equal sign ' = '.)
  172.  
  173. 3.2.6: En-passant:
  174. No explicit indication is used for en-passant captures.
  175.  
  176.  
  177. 3.2.7: Commentary
  178.  
  179. PGN comments are enclosed in braces  { and }  or else begin with a semicolon
  180. ';'.  A semicolon begins a rest-of-the-line comment.  There are no rules 
  181. regarding where ordinary comments should be placed in the text, except they
  182. need to be separated from moves and other elements by at least one space or
  183. newline.  FileMate only allows comments in the movetext section. 
  184.  
  185. Any of the six suffix-annotations "! ? !! !? ?! ??" may be appended to a play.
  186.  
  187. NAGs (Numeric Annotation Glyphs)
  188.  
  189. NAGs are PGN-defined move annotations which have the form of a dollar sign
  190. immediately followed by a number from 1 to 139 (currently).  A NAG must be 
  191. separated from a play by at least one space, e.g. 16. Nd2 Bxe2 $19.
  192.  
  193. A list of 139 annotations are defined in the PGN specifications document.
  194. (Note: The list of NAG's published in the PGN specs. is said to be
  195. "preliminary in nature".)  Although the intended useage isn't discussed, I
  196. presume they are intended to promote standardization of program-generated
  197. annotation...  An analysis program would generate NAG's and output them
  198. embedded in the movetext.  Then, a viewing program would read the NAG codes 
  199. and somehow indicate their meaning to the user.
  200.  
  201. Result indications:
  202. The following are recommended:
  203.    1-0       (White wins)
  204.    0-1       (Black wins)
  205.    1/2-1/2   (Draw)
  206.    *         (The game is not finished, or the result is unknown)
  207.  
  208. Some other result strings have been used, and are recognized by the program:
  209.    1/2  ╜-╜  +-+    (Draw)
  210.  
  211.     
  212. 3.2.8: Variations
  213.  
  214. Quoting from the PGN specifications...
  215.  
  216.    >>8.2.5: Movetext RAV (Recursive Annotation Variation)
  217.  
  218.    An RAV (Recursive Annotation Variation) is a sequence of movetext
  219.    containing one or more moves enclosed in parentheses.  An RAV is
  220.    used to represent an alternative variation.  The alternate move
  221.    sequence given by an RAV is one that may be legally played by first
  222.    unplaying the move that appears immediately prior to the RAV.
  223.    Because the RAV is a recursive construct, it may be nested.<<
  224.  
  225. Example:
  226.  
  227. 1. e4 e6 2. d4 d5 3. Nc3 Nf6 4. Bg5 dxe4 5. Nxe4
  228.    (5. Bxf6 gxf6 6. Nxe4 f5 7. Nc3
  229.       (7. Ng3 c5!)
  230.    7...Bg7
  231.       (7...c5 8. d5!)
  232.    8. Nf3 O-O 9. Qd2 c5 10. dxc5 Qa5 11. Nb5 Qxd2+ 12. Nxd2
  233.    Na6 13. c3 Nxc5 14. Nb3 Nxb3 15. axb3 a6)
  234. 5...Be7 6. Bxf6
  235.  
  236. There are no rules regarding line breaks and indentation.  FileMate allows
  237. you to set breaks and indents for variations and comments.
  238.  
  239.  
  240. 3.2.9: Partial Games
  241.  
  242. Recorded games which do not start at the initial position are called
  243. "partial games".  FEN (Forsyth-Edwards Notation) is an extension of PGN
  244. which specifies how to write partial games.
  245.  
  246. Partial games are useful for relatively efficient recording of chess problems.
  247. Since FEN is a text format, it can be read by both people and software.
  248.  
  249. The game header must have two fields: SetUp and FEN.  The starting position is
  250. described by a character string in the FEN value.
  251.  
  252. Example:
  253.  
  254. [Event "?"]
  255. [Site "Pick of the best Chess Problems, Paperfronts."]
  256. [Date "1994.??.??"]
  257. [Round "?"]
  258. [White "Chess Puzzle #192"]
  259. [Black "?"]
  260. [Result "1-0"]
  261. [SetUp "1"]
  262. [FEN "6b1/B1bR4/B1Q5/p7/2n1p3/2k5/1R6/K7 w - - 0 29"]
  263.  
  264. 29. Qb5 $1 {Threatening 30.Qb3#} 29... Ne5 (29... Nb6 $5 30. Qxa5#) (
  265. 29... Nd6 $5 30. Qe5#) (29... Nxb2 $5 30. Qxb2#) 30. Bd4# 1-0
  266.  
  267. The FEN string contains the following information...
  268. 1. piece placement 
  269. 2. whose turn it is to move
  270. 3. whether or not castling will be possible
  271. 4. the en-passant target square, if any
  272. 5. halfmove clock - the number of plys since the last pawn move or capturing
  273.    move.
  274. 6. the starting fullmove number
  275.  
  276. The first 4 items are important.  Filemate ignores the halfmove clock.  It
  277. will use the fullmove number in the text display.
  278.  
  279. A detailed description of FEN can be found in the PGN specifications document.
  280. However, you can enter all the FEN information by using FileMate's position
  281. setup dialog (except 5.).  The program will automatically write and read FEN
  282. data, so you don't have to.
  283.